Repository navigation
docs(runbook): give docs/ a front door for a successor (#124) - #287
Merged
Merged
Conversation
The runbooks are written for someone competent who does not know this estate, and they are good at it. Nothing addressed that person directly: no page saying what this estate is, what to check on day one, or which runbook to open in what order. That is the difference between "the documentation is good" and "someone else could pick this up". It matters because of where the alternative points. ADR-0011 tiers the household's documentation — a printed card, the wiki on oracle, and a private mirror of that wiki — and none of those three is this. The wiki was built to let the family operate the estate and that audience cannot run pfSense and VLANs from a wiki page, so the realistic reader for deep operational docs is a technical trustee or a paid MSP arriving cold. This repository is where they land, and it had no entry point. docs/runbooks/successor-handover.md orders what already exists rather than restating it: what the estate is in a paragraph, day one in seven steps, what fails soonest if nobody touches anything, where the secrets are and what is not among them, what can be switched off and what cannot, and a reading order. Every claim links to the document that owns it, and that document is the authority when the two disagree. Two sections carry more than an ordering. "What fails soonest" is the one that existed nowhere. The three entries at the top of it are all failures of notification — an alert channel pointed at a destination the successor does not own, a heartbeat watcher on someone else's free-tier account, an unproven key backup — and every one is silent from inside the estate. The certificate, the UPS pack and the unbatteried monitoring path follow, each with the alert that actually watches it. #77 and #93 are named as closed, because a successor reading the older issues will find both described as outstanding and should not go looking for finished work. "Where the secrets are" states what the SOPS file does not hold, which is the half a handover actually turns on: no device admin password is in this repository in any form, the CA key is host-local and gitignored, and the alert destinations live in an account. #106 — one key, one holder, one copy — is quoted as the open issue it is, since a successor who cannot decrypt has nothing. README gets the pointer and a nav entry, and its ADR and runbook counts are corrected — they read fourteen and twelve against 22 and 19, and adding a runbook made the second one wronger. Closes #124 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…over-docs-68de73 # Conflicts: # README.md
Gerrrt
added a commit
that referenced
this pull request
Oct 10, 2026
…WM and RDP baked in (#1108) (#1114) * docs(dotfiles): record the first complete Windows run on dot-windows (#1108) dotfiles-doctor at the console read 28 ok, 1 warn (git identity), 0 fail, after one upstream bug was worked around: dotfiles-Windows#286, the PSReadLine 2.3.6 pin loaded beside pwsh 7.6's in-box 2.4.5. §4 now has that workaround (psmux included), the one-off #287 cache race, GlazeWM's UAC prompt, the SSH-vs-console doctor gap, the WSL result and the slow noVNC. The as-run table and changelog record the run. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(dotfiles): bake GlazeWM, the run's one UAC prompt, into dot-windows (#1108) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(dotfiles): the #286 workaround names tester's module path, not SYSTEM's (#1108) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(dotfiles): Remote Desktop on dot-windows from the Hicks workstations (#1108) noVNC is slow to every guest on Saruman. §3's bake now turns on RDP with NLA, disables Windows' any-address Remote Desktop rules, and admits 3389 from 10.0.50.80/.90/.102 only, with tester in Remote Desktop Users. §4 runs the layer over RDP. ADR-0090's NOTE records the exception to ADR-0077's key-only SSH and why it is acceptable on this one guest. Applied to 198 and verified from the Mac; the as-run table and changelog record it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This was referenced Oct 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #124.
docs/had no entry point for a successor. The runbooks are written for someone competent who does not know this estate — the right reader — but nothing addressed that person: no page saying what this estate is, what to check on day one, or which runbook to open in what order.The page
docs/runbooks/successor-handover.mdorders what already exists rather than restating it. Every claim links to the document that owns it, and that document is the authority when the two disagree.oracle, a private mirror of that wiki — and none of those three is this. Stated as a correction of a real conflation rather than as a slogan: the third tier is Lemmiwinks' GitHub mirror, not HomeLab.morpheusis routing, DHCP and the only advertised resolver;neocarries every VLAN; nothing in the house depends on the observability stack; Hicks is where you administer from and is not the only path into management.The two sections that carry more than an ordering
What fails soonest is the part that existed nowhere. The three entries at the top are all failures of notification — an alert channel pointed at a destination the successor does not own, a heartbeat watcher on someone else's free-tier account, an unproven key backup — and every one is silent from inside the estate; there is no dashboard on which they look wrong. The certificate, the UPS pack and the unbatteried monitoring path follow, each with the alert that actually watches it.
Where the secrets are states what the SOPS file does not hold, which is the half a handover actually turns on: no device admin password is in this repository in any form, the CA key is host-local and gitignored, and the alert destinations live in an account. #106 is quoted as the open issue it is — a successor who cannot decrypt has nothing.
Two premises in the issue that had gone stale
The issue lists "nothing schedules any backup, digest check or key verification (#77)" and the UPS battery (#93) among what fails soonest. Both are closed, and the page says so explicitly rather than silently omitting them — a successor reading the older issues will find both described as outstanding and should not go looking for finished work. The issue also says "nine ADRs"; there are 22.
README
A nav entry, a short pointer under the intro, and the runbook list in the layout tree. Its ADR and runbook counts are corrected while I am there: they read fourteen and twelve against 22 and 19, and adding a runbook made the second one wronger.
Verification
Every relative link and in-page anchor in the new file was resolved against the tree. The new page joins
docs/runbooks/*.md, whichcheck_docs.pyglobs intoPROSE, so it is now covered by the counted-claim and image-pin assertions like every other present-tense document — it deliberately carries no rule, dashboard or panel counts of its own.Full
make validatewas not run here:promtoolis not on this host and the stack does not run in a worktree, so the container-backed checks would skip rather than pass. CI is the authority on those.🤖 Generated with Claude Code